RWTH - Mindstorms NXT Toolbox Version 2.00 beta Guidelines
This document describes the main changes in version 2.00 beta of this toolbox and gives a short introduction on how to use them!
Contents
The communication layer
To establish a connection to an NXT device, the following functions are provided:
- COM_OpenNXT
- COM_OpenNXTEx
- COM_CloseNXT
- COM_SetDefaultNXT
- COM_GetDefaultNXT
They replace the old BT_ functions from toolbox version 1.00. Also BT_CreatePacket, BT_SendPacket, and BT_CollectPacket have been replaced by COM_CreatePacket, COM_SendPacket, and COM_CollectPacket. These changes are only to be consistent with the naming scheme, the usage of these functions has not changed. The prefix COM_ stands for "communication functions".
The most important change in toolbox version 2.00 is the support for USB connections. On Windows systems, the Mindstorms NXT device driver (called "Fantom") has to be installed. On Linux systems, the free open source library libusb is used. Additionally, the devices' access rights have to be modified so that the NXT bricks appear in /dev/.
Opening connections and retrieving handles
The following way is recommended to open a connection:
h = COM_OpenNXT('bluetooth.ini', 'check'); COM_SetDefaultNXT(h);
This replaces what looked like this in toolbox version 1.00:
h = BT_OpenHandle('bluetooth.ini', 'check'); BT_SetDefaultHandle(h);
The big difference however is that COM_OpenNXT will also look on the USB bus for an NXT. If it succeeds, the USB connection will be used, otherwise a Bluetooth connection is created. This makes the above example work with both Bluetooth and USB connections without having to change the code! Just plug or unplug the USB cable to your NXT device. If USB is present, it will be used, if not, Bluetooth comes into action.
The handle struct
In version 1.00 our NXT handle was just a variable (serial object on Windows, file handle on Linux). Now, we have a fairly large struct, containing lots of useful (and necessary) information. The users do NOT have to use this handle in any way but to pass it to functions, just as they could in earlier versions. All other functions and commands just work as they did before!
The handle contains some function-handles (to store dynamic information using the principle of function closures). However they are not to be used by normal users! It will later be explained to the advanced user how to retrieve connection statistics (how many bytes and packets were sent or received).
For now, the message is: We have got a huge handle struct, look at it if you want, but do not modify it. It does not matter what is in there, everything just works, so no need to bother!
Default handles
To put it simply: BT_SetDefaultHandle and BT_GetDefaultHandle have just been replaced by COM_SetDefaultNXT and COM_GetDefaultNXT. So adapt your code, the syntax is exactly the same.
Closing handles and cleaning up
The two functions BT_CloseHandle and BT_CloseAllHandles have been combined to the one function COM_CloseNXT.
To clean up after using your NXT-handle, just call
COM_CloseNXT(h); clear h % this is not necessary but good practice, so I recommend it
Instead of BT_CloseAllHandles we now have:
COM_CloseNXT all
The old way of closing just a specific serial port has been mapped to this syntax:
COM_CloseNXT('all', 'bluetooth.ini');
New debug functions
The way the function textOut behaves has not changed. But it was quite uncomfortable to use global DisableScreenOut in order to enable or disable debug messages. So we now have helper functions:
DebugMode on % do something DebugMode off
DebugMode(state) is a method that can set the debug-state, but when called without any arguments, DebugMode() will return the current setting. So if we want to remember and restore the previous state, we can do so by:
OldDebugState = DebugMode(); % remember old state DebugMode on % force it to always be on % do something with guaranteed debug infos DebugMode(OldDebugState); % be polite, reset to old state
To check if debug messages are enabled, use:
if isdebug % we know debug mode is set to 'on' end%if
This is essentially the same as
if strcmpi(DebugMode(), 'on') % we know debug mode is set to 'on' end%if
but since MATLAB is not very fast with string comparisons, I recommend to use isdebug where time is critical. Also it is easier.
Please note the similarity to MATLAB's built-in functions hold on, hold off and ishold.
New "snapshot" mode for ultrasonic sensor
The function OpenUltrasonic has been updated with the additional optional parameter 'snapshot'. When set, the functions USMakeSnapshot and USGetSnapshotResults enable you to send out a single "ping" signal, and let the sensor record up to 8 following echos. All 8 recordings can then be retrieved in one step. See function help for further information. An example might look like this:
port = SENSOR_4; OpenUltrasonic(port, 'snapshot'); % send out the ping USMakeSnapshot(port); % wait some time for the sound to travel pause(0.1); % 100ms is probably too much, calculate using c_sound ;-) % retrieve all the echos in 1 step echos = USGetSnapshotResults(port); CloseSensor(port);
New I/O Map Module access
New system functions NXT_ReadIOMap and NXT_WriteIOMap have been implemented, enabling low-level access to the NXT's internal I/O map module registers. For easier usage, some high level functions have been implemented. They all start with the prefix MAP_, see list of functions and their documentation for further information.
Note: These new functions do not (yet?) work under Windows when using USB connections. They do however work with Bluetooth under Windows. On Linux systems, both USB and Bluetooth connections are supported for I/O map module access.
Conclusion
To sum up all necessary changes for your programs:
- Replace BT_OpenHandle with COM_OpenNXT, syntax stays the same. If you want, you can also use COM_OpenNXTEx, but then a more complex syntax comes into place.
- Replace BT_SetDefaultHandle with COM_SetDefaultNXT and BT_GetDefaultHandle with COM_GetDefaultNXT.
- Replace BT_CloseHandle(h) with COM_CloseNXT(h).
- Replace BT_CloseAllHandles() with COM_CloseNXT('all').
- Replace BT_CloseAllHandles('bluetooth.ini') with COM_CloseNXT('all', 'bluetooth.ini').
- Instead of modifying the global variable DisableScreenOut for debug-messages by textOut, the two new easy functions DebugMode() and isdebug are available.
Contact
Please feel free to contact me by mail if you have comments:
linus (dot) atorf (at) rwth-aachen (dot) de
or via http://www.mindstorms.rwth-aachen.de
Version 1.01 of this document, Linus Atorf, July 18th 2008